Universal OS 1.13 for TI-89 and TI-92 Plus
Copyright (c) 2000. All rights reserved.
Available on www.ticalc.org and www.ti-fr.org

The method used by Universal OS 1.11 to imporove the grayscales works
but the results aren't the same on all the calculators, so that it was
sometimes worse than under Universal OS 1.10&-.

This new version, except a few bugfixes, reuses this method but the user
now adjust the quality with [<>(diamond)]+[<] and [<>]+[>]. The "adjust"
program permits to distinguish the flaws well so it can be used for the
adjustment : in fact, it is a simple gray screen. It uses gray4lib and,
with other kernels, it may be useful to test other versions of gray4lib
or graphlib, since the gray4lib of Doors/TEOS uses graphlib.

I) Introduction

Universal OS is a kernel. It works on all calculators and it is 'fully'
(see the 'Features' section) compatible with DoorsOS II 0.96. You can
archive any library and run any program greater than 8 kb on ROM 2.0x
directly. Grayscales work on HW1 and HW2 if the program uses a recent
library to manage them : for example, graphlib, gray4lib or gray7lib
(8-level grayscales aren't supported on HW2).

Universal OS isn't finished, and there are still a few restrictions.

Archive contents:
- install: to install and to uninstall Universal OS
- kernel: the kernel (necessary only for the installation)
- adjust: displays a gray screen, to test the grayscales

Universal OS is freeware. The distribution of Universal OS is
encouraged, as long as all the files are kept together, and unmodified
from the form in which they were originally released.

II) Installing and Using Universal OS

If you have a HW2 2.03 calculator, you must use HW2Patch.

Copy all the files to a folder on the calculator. Launch "install".
Once installed, you can run any assembly program.

To uninstall Universal OS, you must run the install program again (and
it will automatically detect that you want to uninstall). Using the
included install program is the only way that you can uninstall
Universal OS correctly.

NOTES: - The file "kernel" must be in the same folder as "install".
       - Use Universal OS at you own risk and I cannot be held
         responsible for any damage done to your calculator.
       - DON'T INSTALL DoorsOS after installing Universal OS.
       - DON'T UNINSTALL Universal OS with "Doors\uninstal".
       - Universal OS doesn't automatically replace an old kernel for
         reasons of security.

III) Features

- Util, userlib, gray4lib, gray7lib (except on HW2), graphlib and
  linelib have been reprogrammed and integrated (i.e. in the 'kernel'
  variable) into Universal OS.
  ANY EXTERNAL LIBRARY WHICH HAS ONE OF THESE NAMES WILL BE IGNORED.
- adjustment of the grayscales with [<>]+[<] et [<>]+[>] on HW2 : this
  is possible only if the grayscales are activated and managed by
  gray4lib/graphlib.
- You can launch the program called 'doors' with [Shift]+[ON].
  Differences with Doors :
  - [Shift]+[ON] works more often.
  - the 'doors' program can be archived.
- Any reset is detected and a menu is displayed :
  1) reset
  2) turn off
  3) send all the vars to another calc
  Notes :
  - thanks to VTI, you can also send to a computer
  - the calc may not manage to stay off : if it stays off more than two
    seconds, it's ok. I'll try to find a solution.
  - WARNING ! This functionality doesn't guarantee that the sent vars
    don't crash the destination calc. Indeed, they may have been
    modified if there has been a crash. The best would be to save the
    content of the destination calc.
- You can turn off the calculator at any time (even if AMS is busy) by
  pressing [2nd]+[ON].
- You can exit an assembly program at any time by pressing ESC+ON.

- Universal OS doesn't recover memory left unfreed by programs.
  Personally, I don't see how to know if a handle must be freed or not.
  Besides, the algorithm used by DoorsOS isn't perfect.
- The reloc functions aren't supported. For example, prosit won't work.
  (I think prosit is the only one.)
- The userlib::exec function doesn't support zipped programs. This is
  the only difference with the DoorsOS II 0.96 libraries.

IV) Notes For Programmers

These remarks also concern programmers who use DoorsOS.

* The exit point:

Imagine this case: Library X uses library Y in its exit point and Y uses
X in its exit point. If X or Y needs any information it had deleted,
there is a bug, no matter how sophisticated the anti-crash protection
is. My message is that you shouldn't use libraries in your exit point.

* Compatibility:

To prevent problems with new ROM versions, avoid constants. Preferably,
use RAM CALLS and libraries, THEN ROM CALLS. Indeed, TI has changed a
few ROM CALLS on ROM 2.xx : for example, _ROM_CALL_15C doesn't point to 
EM_blockErase, but to a keyboard variable (I hope that's the only
change). Don't use LCD_MEM if the program is in grayscale!  Use the
exported variables.

Be sure that your program is compatible with the TI-89 and the TI-92+.
The concern here is the keyboard.

* The doorsos.h header file:

Don't use:
- doorsos::EM_blockErase	equ	_ROM_CALL_15c
- APD_INIT	equ	LCD_MEM+$F10
  APD_TIMER	equ	LCD_MEM+$F14
  APD_FLAG	equ	LCD_MEM+$F42
  but the userlib::get_APD and userlib::get_ADP functions.
- doorsos::ER_throw macro
   dc.w $A000+\1
   endm
  For security, and even if I improved the anti-crash protection, so
  that your program exits more cleanly.

* The ROM functions:

Consider that all ROM functions destroy D0-D2/A0-A1.
This explains why Falldown and Tetris don't save names on ROM 2.xx. So,
be careful with the WriteStr and WriteStrA macros.

VI) Known Problems

This kernel uses the supervisor stack and saves some information in it.
The problem is that some buggy programs write in it. With other kernels,
this isn't a problem because they don't save anything in it, but with
Universal OS, the calculator may crash.

VI) To do

- supports the reloc functions
- finish the userlib::exec function so that it can launch zipped
  programs
- prevent the graphical functions from writing out of the selected plane
  if the coordinates are bad and report the bug using a message

VII) History

05/28/2000 : Universal OS 1.13
- HW2 89&92+ : the adjustment of the grayscales with [<>]+[<] and
  [<>]+[>] should work more often.
- The idle_loop no longer modify the busy flag (it doesn't even clear
  it, contrary to the DoorsOS libraries).

05/25/2000 : Universal OS 1.12
- HW2 89&92+ : adjustment of the grayscales with [<>]+[<] and [<>]+[>]
  (adjust permits to estimate the quality of the grayscales well).
- HW2 : bugfix in graphlib::gray4.
- The use of [Shift]+[ON] no longer disables the basic from an assembly
  program : for example, it was impossible to launch a basic program
  from "doors".

05/11/2000 : Universal OS 1.11
- Grayscale improved on 89 (thanks to Olivier Serres).
- [Shift]+[ON] supported : it launches the 'doors' program.
- Userlib updated : userlib::password added.
- Grayscale routines updated :
  - initialization of the bitplanes.
  - page flipping support in graphlib.
- All problems with return values are solved (there were two bugs : one
  in AMS 2.0x, and another in Universal OS).
- Universal detects if HW2Patch is necessary.
- On HW2 : the uninstallation doesn't reactivates the 8 kb harware limit
  any more if the method which doesn't modify the ROM has been chosen.
- Bugfixes.

02/27/2000 : Universal OS 1.10
- You can save all your data just before a reset.
- [2nd]+[ON] works even if AMS is busy.
- the kernel file can be archived.
- It is possible not to set a password.
- Fixed bugs in:
  - graphlib::clr_scr2 (!)
  - the grayscale routines.
  - kernel::exec

01/08/2000 : Universal OS 1.02
- Libraries can be in any folder.
- Fixed a bug in graphlib::clr_scr2.

01/03/2000 : Universal OS 1.01
- Fixed bugs in:
  - doorsos::kb_globals (_RAM_CALL_010)
  - util::clr_scr
  - userlib::lockcalc
  - checksum of phoenix

01/02/2000 : Universal OS 1.00

VIII) How to contact me

You can e-mail me at: <Julien.Muchembled@netcourrier.com>

Please report any and all bugs you find while using the kernel, and
please don't forget to give me a precise description of what you did and
what happened. However, I have a lot of work so I won't answer if the
problem mentionned is already solved or known, or if I decide to do a
global message in the doc of a future version.